Getting Started & Total Build Isolation

Welcome to the setup and getting started guide for Void-Builder. This document details the zero-dependency, self-contained build architecture of Void-Builder, system requirements, and step-by-step build walkthroughs.

1. Zero Host Dependency & Total Isolation Architecture

Unlike traditional ISO building tools that require installing numerous host system packages (such as xbps-install, qemu-user-static, or dracut on the host machine), Void-Builder implements complete build isolation:

How Total Isolation Works:

Self-Contained Static Binaries: On initial run, ToolchainManager automatically downloads isolated static binaries (xbps-install.static and proot) directly into the local void_builder/tools/ directory.
No Host Package Installation Needed: You do NOT need to install any building tools, package managers, or chroot utilities via apt, pacman, dnf, zypper, or xbps-install on your host OS.
Isolated Chroot Execution (proot): Chroot management and cross-architecture command executions are handled in user-space via proot and isolated pseudo-filesystem mounts.
Host Distribution Agnostic: Void-Builder runs identically on Void Linux, Debian, Ubuntu, Arch Linux, Fedora, openSUSE, Alpine, or any other Linux distribution with Python 3.10+ installed.

2. Requirements

Host Requirements

Python: Python 3.10 or higher.
Disk Space: 10 GB free space on a local Linux filesystem (EXT4, Btrfs, XFS).
RAM: 4 GB minimum.

3. Automatic Static Toolchain Resolution

When ToolchainManager.setup() executes, it automatically manages the toolchain:

void_builder/tools/
├── proot                              # User-space chroot/emulation binary
└── usr/
    └── bin/
        ├── xbps-install.static        # Static XBPS installer binary
        ├── xbps-rindex.static         # Static XBPS repository indexer
        └── xbps-query.static          # Static XBPS query tool

If these static tools are missing or if --update-toolchain is specified, Void-Builder fetches the latest verified static releases directly from official mirrors into void_builder/tools/.

4. Cross-Architecture Host Helper (Optional)

When cross-building for foreign CPU architectures (e.g. building an aarch64 or rpi image on an x86_64 host), the helper script setup_host_build_env.sh can optionally configure kernel binfmt_misc user-mode emulators:

sudo ./setup_host_build_env.sh

5. Verification & First Build Walkthrough

Step 1: Configuration Validation

Audit all JSON configuration profiles and dynamic package rules without building:

python3 cli.py --check

Outputs:

🔍 Validating configuration for target architecture 'x86_64'...
2026-07-22 11:40:00 - ConfigLoader - INFO - Starting configuration assembly for x86_64...
2026-07-22 11:40:00 - ConfigLoader - INFO - Applied dynamic package rules from package_rules.json successfully.
2026-07-22 11:40:00 - ConfigLoader - INFO - Configuration assembly completed successfully.
✅ Configuration is VALID!
Summary:
  - Target Architecture: x86_64
  - Desktop Profile:     base
  - Total Packages:      136
  - Enabled Services:    dbus, NetworkManager, polkitd, bluetoothd, cupsd, avahi-daemon, sshd, chronyd, alsa, acpid, elogind, wpa_supplicant

Step 2: Non-Root Simulation (Mock Mode)

Simulate building an x86_64 ISO with XFCE desktop environment:

python3 cli.py x86_64 -d xfce --mode mock

This verifies the build tree, packages list, and bootloader configuration without needing root privileges.

Step 3: Production Real ISO Build

Execute a production build:

sudo python3 cli.py x86_64 -d xfce --mode real